<!DOCTYPE html>
<html>
<head>
    <title>PDFoutline.py Help</title>
    <meta charset="utf-8" />
</head>
<body>
    <h1>PDFoutline.py Help</h1>
    <h2>Maintaining a PDF's Bookmarks and Meta Information</h2>
    <p>This is a Python script for maintaining a PDF document's bookmark tree, also known as the "table of contents (TOC)".</p>
    <p>It is based on <b>PyMuPDF</b> version 1.9.1 (or above) and <b>wxPython</b> version 3.0.2 (or above).</p>
    <section id="input">
        <h2>Input</h2>
        <p>It can be invoked via CLI and be given a PDF file name as parameter. If invoked without parameter, the standard file open dialog of the system will be presented to locate a PDF file.</p>
        <p>Encrypted files are supported for input: A password entry dialog will ask for the password to access the file.</p>
    </section>
    <section id="output">
        <h2>Output</h2>
        <p>Once you have finalized the new TOC version, you can save the result in the current file (the PDF incremental update technique is used in this case) or under a new filename. If the input has been decrypted or if it has an inconsistent PDF file structure, you must save your work under a new filename. Encryption is not supported as an output option.</p>
        <p>At any time, you may interrupt your work: Press the <font color=\"red\"><b>Check Data</b></font> button before quitting. The current state of your work will be saved under <b><code>&lt;PDF-filename&gt;.json</code></b> in the PDF's directory. The PDF itself will remain unchanged. On resuming work, this parameter file will be offered to restore the previous state. If you deny, it will be deleted. It will also be deleted, if you press <font color=\"red\"><b>SAVE</b></font>. The parameter file will be updated every 60 seconds while the program is awaiting input <b>("auto-save feature")</b>.</p>
    </section>
    <section id="main-dialog">
        <h2>Main Dialog</h2>
        <p>The program's dialog consists of the following main parts:</p>
        <p>The <b>right part</b> is used to display the current PDF page. If bookmarks point to this page, their target location is indicated as a horizontal red line. You can navigate in the file via buttons, the mouse wheel or by entering a specific page number.</p>
        <p>The <b>upper left part</b> consists of a grid where the TOC is displayed in tabular format.</p>
        <p>The <b>lower left part</b> displays file and document meta information.</p>
    </section>
    <section id="maintaining-file-information">
        <h2>Maintaining File Information</h2>
        <p>You can change some metadata fields (<b>author</b>, <b>title</b>, <b>subject</b> and <b>keywords</b>), others are automatically set:</p>
        <ul>
            <li><b>/CreationDate</b> = current date-time (if original is invalid)</li>
            <li><b>/ModDate</b> = current date-time</li>
            <li><b>/Producer</b> = "PyMuPDF" (if original is empty)</li>
            <li><b>/Creator</b> = "PDFoutline.py" (if original is empty)</li>
        </ul>
    </section>
    <section id="maintaining-the-toc">
        <h2>Maintaining the TOC</h2>
        <p>Upon program start, existing bookmark (outline) entries are extracted using method <b><code>getToC(simple = False)</code></b>. This information is displayed in the TOC grid in tabular format. It contains the four columns <b>Level</b>, <b>Title</b>, <b>Page</b> and <b>Height</b>. Any of this information can be changed any time without changing the underlying PDF. 
	If the PDF currently does not contain bookmarks, a dummy entry will be displayed in the grid.</p>
    </section>
    <section id="maintaining-toc-rows">
        <h2>Maintaining TOC Rows</h2>
        <ul>
            <li><b>Delete a row:</b> CTRL+Click row number.</li>
            <li><b>Duplicate a row:</b> DoubleClick row number. The new row will be inserted above the current one.</li>
            <li><b>Move a row:</b> left-click and hold row number, then drop it at the desired location.</li>
        </ul>
        <p>There is no separate <i>new row</i> function. If a PDF contains no outline at all, a dummy bookmark is displayed in the grid to serve as a template for new entries.</p>
    </section>
    <section id="maintaining-row-cells">
        <h2>Maintaining Grid Cells</h2>
        <p>You can overtype any cell at any time. Pressing <font color=\"red\"><b>ENTER</b></font> will move to the next cell to the right (wrapping around to next row). On double-clicking any cell that is <b>not currently selected</b>, the corresponding PDF page will be displayed. The following explains any special cell behaviors:</p>
        <ul>
            <li><b>Title:</b> Text entered will be indented automatically depending on the entry's level. The column width will be auto-adjusted.</li>
            <li><b>Height:</b> This denotes the distance of the bookmark's destination from the bottom of the page in so-called user units (PDF terminology). This usually equals pixels and 72 pixels equal one inch. It should be noted, that MuPDF (and PyMuPDF) correctly handles a page's presentation in terms of its <b>CropBox</b> (if present, <b>MediaBox</b> otherwise). The <b>Height</b> information you supply here will therefore be translated into the following destination PDF dictionary: <code><b>[page /XYZ 0 height 0]</b></code>. If you type a number in this cell, the entry's page is automatically displayed and a red horizontal line indicates the entered height coordinate. If you double-click the cell, the page is also displayed and a slider pops up to let you choose this value. If the PDF's original TOC did not have a <b>Height</b> information, a value of -1 will be displayed initially.</li>
        </ul>
	<h2>Validating Input</h2>
        <p>Error checking your input will <b>only</b> take place when you press <font color=\"red\"><b>Check Data</b></font>. The following will be checked:</p>
        <ul>
            <li>The hierarchy level of row 1 must be 1.</li>
            <li>Hierarchy levels in sequence must not increase by more than 1 (but can decrease by any number).</li>
            <li>Titles must not be empty.</li>
            <li>Page numbers are 1-based and must be in range <code><b>[1, pageCount]</b></code></li>
            <li>Height must be greater than zero and must not exceed the page's height. If height had been initialized with -1, it will be automatically corrected by page height minus 36 pixels (0.5 inches = 1.27 cm).</li>
        </ul>
    </section>
    <section id="finishing-work">
        <h2>Finishing Work</h2>
        <p>Changing TOC information will disable the <font color=\"red\"><b>SAVE</b></font> button. Press <font color=\"red\"><b>Check Data</b></font> to validate your input and to enable the save button. As mentioned above, <font color=\"red\"><b>Check Data</b></font> / <font color=\"red\"><b>QUIT</b></font> will save your input but will not change the PDF.</p>
	<h2>Exception Handling</h2>
	If an exception occurs while saving the PDF, traceback information will be displayed and also saved under filename <b><code>&lt;PDF-filename&gt;.txt</code></b> in the PDF's directory.
    </section>
</body>
</html>